﻿// ===============================================================================
// IMarkup.cs
// EOS Web Framework
// ===============================================================================
// Copyright (c) EOS Development Group. All rights reserved.
// ===============================================================================

namespace EOS.Framework.Web.Mvc
{
    using System;

    /// <summary>
    /// Represents a markup file (template).
    /// </summary>
    public interface IMarkup : ICloneable
    {
        /// <summary>
        /// Occurs when a control is attached to the markup.
        /// </summary>
        event EventHandler<ControlAttachedEventArgs> ControlAttached;

        /// <summary>
        /// Gets or sets the container, where the markup is assigned to.
        /// </summary>
        /// <value>The container.</value>
        Container Container { get; set; }

        /// <summary>
        /// Gets or sets the child markup.
        /// </summary>
        /// <value>The child markup.</value>
        Markup Child { get; set; }

        /// <summary>
        /// Replaces the key with the specified value.
        /// </summary>
        /// <param name="key">The key to replace. Cannot be null or
        /// empty or contains only blanks.</param>
        /// <param name="value">The value string. Cannot be null (Nothing in Visual Basic).</param>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="key"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="value"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException"><paramref name="key"/> is empty or 
        /// contains only blanks.</exception>
        /// <remarks>If the markup contains a value with the following pattern #{[KEY]} it can
        /// be replaced with this method.</remarks>
        void SetValue(string key, string value);

        /// <summary>
        /// Replaces the key with the specified value, which is formatted with the specified arguments.
        /// </summary>
        /// <param name="key">The key to replace. Cannot be null or
        /// empty or contains only blanks.</param>
        /// <param name="value">The value string. Cannot be null (Nothing in Visual Basic).</param>
        /// <param name="args">The arguments for string formatting.</param>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="key"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="value"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException"><paramref name="key"/> is empty or
        /// contains only blanks.</exception>
        /// <remarks>If the markup contains a value with the following pattern #{[KEY]} it can
        /// be replaced with this method.</remarks>
        void SetValue(string key, string value, params object[] args);

        /// <summary>
        /// Attaches an control to the markup.
        /// </summary>
        /// <param name="key">The key of the tag, where to attach the control to. Cannot be null or
        /// empty or contains only blanks.</param>
        /// <param name="control">The control to attach.</param>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="key"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="control"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException"><paramref name="key"/> is a string
        /// of length 0 or contains only blanks.</exception>
        void Attach(string key, Control control);

        /// <summary>
        /// Attaches an control to the markup.
        /// </summary>
        /// <param name="key">The key of the tag, where to attach the control to. Cannot be null or
        /// empty or contains only blanks.</param>
        /// <param name="control">The control to attach.</param>
        /// <param name="throwExceptions">if set to <c>true</c> the method throws an exception, if the
        /// key cannot been found.</param>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="key"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="control"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException"><paramref name="key"/> is a string
        /// of length 0 or contains only blanks.</exception>
        void Attach(string key, Control control, bool throwExceptions);

        /// <summary>
        /// Hides the tag with the specified key.
        /// </summary>
        /// <param name="key">The key of the tag to hide. Cannot be null or
        /// empty or contains only blanks.</param>
        /// <exception cref="ArgumentNullException"><paramref name="key"/> is null 
        /// (Nothing in Visual Basic).</exception>
        /// <exception cref="ArgumentException"><paramref name="key"/> is a string
        /// of length 0 or contains only blanks.</exception>
        void Hide(string key);

        /// <summary>
        /// Hides the tag with the specified key.
        /// </summary>
        /// <param name="key">The key of the tag to hide. Cannot be null or
        /// empty or contains only blanks.</param>
        /// <param name="throwExceptions">if set to <c>true</c> the method throws an exception, if the
        /// key cannot been found.</param>
        /// <exception cref="ArgumentNullException"><paramref name="key"/> is null
        /// (Nothing in Visual Basic).</exception>
        /// <exception cref="ArgumentException"><paramref name="key"/> is a string
        /// of length 0 or contains only blanks.</exception>
        void Hide(string key, bool throwExceptions);

        /// <summary>
        /// Renders the markup with the given xhtml writer.
        /// </summary>
        /// <param name="writer">The writer for rendering. Cannot be null.</param>
        /// <param name="context">The context object, containing context value.
        /// Cannot be null (Nothing in Visual Basic).</param>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="writer"/> is null (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="context"/> is null (Nothing in Visual Basic).</para>
        /// </exception>
        void RenderMarkup(IXhtmlWriter writer, PageContext context);
    }
}
